home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 076-100 / 094 / audiotools / audiotools.doc next >
Text File  |  1995-03-13  |  3KB  |  94 lines
  1.  
  2.  
  3. RELEASE 2 - AUDIO TOOLS - DOCUMENTATION
  4. ---------------------------------------
  5.  
  6. The RELEASE.2 directory contains the source and executable program
  7. for the second release of the audio tools, called audiotools2.c.  
  8. The example program is called rel2.demo.c.
  9.  
  10. It includes the following functions that are designed to be used by
  11. the casual user as well as a developer.  A one-line description is
  12. provided here, with complete documentation for each following later
  13. in this document.
  14.  
  15. The functions:
  16.  
  17.   port = InitAudio()        initialize the audio routines, get a port
  18.                 for receiving messages from audio routines
  19.   channel = GetChannel(type)    request a channel to use.
  20.   error = FreeChannel(channel)    free a channel that you have been given.
  21.   FinishAudio(port)        end the use of audio routines and return
  22.                 the port you received from audio routines
  23.  
  24.   error = StopChannel(channel)    temporarily halt a channel you own
  25.   error = StartChannel(channel) start your channel up again.
  26.   error = FlushChannel(channel) empty the queue of a channel from any notes
  27.                 it is playing or is going to play.
  28.   error = ResetChannel(channel) reset a channel
  29.  
  30.   PlayNote( ... parameters ...) queue up a specific note number to be played
  31.                 by one of your channels.
  32.   PlayFreq( ... parameters ...) queue up a specific frequency instead of note.
  33.  
  34.   IsThatMyChan(channel)        see if your task still owns a particular
  35.                 channel (audio system allows stealing of
  36.                 channels if they are not locked at a high
  37.                 enough priority).  
  38.  
  39.   note = MayGetNote(port, flag) see if a note you marked has begun to play.
  40.                 possibly put task to sleep if it has not.
  41.                 good for synchronizing graphics and sound.
  42.  
  43.   SetPV(channel,per,vol)    Set the period and/or volume of a channel
  44.                 that is already playing a waveform.  Limited
  45.                 use (except for volume, that is; see the
  46.                 article text to see why you may not want to
  47.                 use this routine to set the period.  In fact,
  48.                 I will probably add routines that do volume
  49.                 and period separately - routine has to
  50.                 be able to read what is now playing to
  51.                 be able to modify it properly.)
  52.  
  53.  
  54. USING THE ROUTINES
  55. ------------------
  56.  
  57. To use the routines, the proper minimal code sequence is:
  58.  
  59.     1. Declare a pointer to a message port:
  60.  
  61.         struct MsgPort *myport;
  62.  
  63.     2. Declare a LONG integer variable to hold a channel number:
  64.  
  65.         LONG channel;
  66.  
  67.     3. Initialize the audio routines, if successful, the init
  68.        returns a pointer to a message port:
  69.  
  70.         myport = InitAudio();
  71.  
  72.     4. Get a channel to use for your output:
  73.  
  74.         channel = GetChannel(-1); 
  75.  
  76.        where -1 means "any" available channel,
  77.        0, 1, 2, or 3 means a specific channel.
  78.  
  79.        If a value of 0, 1, 2, or 3 is returned,
  80.        you have that channel to use.
  81.  
  82.     5. Choose a note or frequency to play, and its duration,
  83.        the waveform to use, and so on (see detailed
  84.        descriptions of PlayNote and PlayFreq).
  85.  
  86.         error = PlayNote(... parameters ...);
  87.  
  88.             or
  89.  
  90.         error = PlayFreq(... parameters ...);
  91.  
  92.  
  93.  
  94.